home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / chooser_gc.doc < prev    next >
Encoding:
Text File  |  1999-10-29  |  12.5 KB  |  355 lines
  1. TABLE OF CONTENTS
  2.  
  3. chooser_gc/--datasheet--
  4. chooser_gc/--styleguide--
  5. chooser_gc/CHOOSER_GetClass
  6. chooser_gc/AllocChooserNodeA
  7. chooser_gc/FreeChooserNode
  8. chooser_gc/GetChooserNodeAttrsA
  9. chooser_gc/SetChooserNodeAttrsA
  10. chooser_gc/--datasheet--                             chooser_gc/--datasheet--
  11.  
  12.      NAME
  13.         chooser_gc -- A popup/dropdown small list selection gadget.
  14.  
  15.      SUPERCLASS
  16.         gadgetclass
  17.  
  18.     REQUIRES
  19.         bevel.image, glyph.image
  20.  
  21.      DESCRIPTION
  22.         A chooser is a small-list selection object.  In its inactive mode it
  23.         looks much like a button or cycle gadget.  When the button is pressed
  24.         using the mouse, a menu displaying the items in the list is displayed.
  25.  
  26.         The chooser operates in either of two modes, pop-up and drop-down.
  27.         Even though the may operate similarly internally, they are for two
  28.         different functions.  Consult the chooser style guide for
  29.         information on how to use these two modes.
  30.  
  31.         Advantages that this class provides:
  32.  
  33.          > Supports window relativity.
  34.  
  35.          > Supports OS 3.0 BOOPSI Gadget HelpTest.
  36.  
  37.          > Cycle2Menu style activation.
  38.  
  39.          > Supports tab-cycle activation and keyboard control.
  40.  
  41.      METHODS
  42.         OM_NEW -- Create the chooser gadget.  Passed to superclass.
  43.  
  44.         OM_SET -- Set object attributes.  Passed to superclass first.
  45.  
  46.         OM_DISPOSE -- Cancels the chooser menu before being passed to
  47.             superclass.
  48.  
  49.         OM_UPDATE -- Set object notification attributes & render.
  50.             Passed to superclass first.
  51.  
  52.         OM_NOTIFY -- Notify object attributes. Passed to superclass last.
  53.  
  54.         GM_RENDER -- Renders the gadget imagry.  Overrides the superclass.
  55.  
  56.         GM_HITTEST -- Determines if mouse is within the gadget rectangle.
  57.             Overrrides the superclass.
  58.  
  59.         GM_GOACTIVE -- Handles activation, pops up the chooser menu.
  60.             Overrides the superclass.
  61.  
  62.         GM_HANDLEINPUT -- Handles input events once active.  Overrides the
  63.             superclass.
  64.  
  65.         GM_GOINACTIVE -- Closes the chooser menu.  Overrides the superclass.
  66.  
  67.         GM_DOMAIN -- Calculates mix/max sizes. Overrides the superclass.
  68.  
  69.         GM_KEYACTIVE -- Activates gadget via keyboard, advances popup
  70.             selection to the next item, if SHIFT is pressed, it selects
  71.             the previous item. Invoked by window.class only.
  72.  
  73.         GM_KEYINACTIVE -- Deactivates gadget. Invoked by window.class only.
  74.  
  75.         All other methods are passed to the superclass.
  76.  
  77.      ATTRIBUTES
  78.  
  79.         GA_ID (WORD)
  80.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET, OM_NOTIFY)
  81.  
  82.         GA_ReadOnly (BOOL)
  83.             Set to TRUE to make the gadget non-selectable, but without
  84.             a ghost pattern.
  85.  
  86.             Defaults to FALSE.
  87.  
  88.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  89.  
  90.         GA_Disabled (BOOL)
  91.             Set to TRUE to disable gadget, FALSE otherwise
  92.  
  93.             Defaults to FALSE.
  94.  
  95.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  96.  
  97.         GA_TextAttr (struct TextAttr *)
  98.             Font to use for the gadget text.
  99.  
  100.             Defaults to the screen's font.
  101.  
  102.             Applicability is (OM_NEW, OM_GET)
  103.  
  104.         CHOOSER_PopUp (BOOL)
  105.             Sets the chooser to work in popup mode.
  106.             Generally this mode is used for selecting an application mode or
  107.             a state from a list of possible values.  This item is mutually
  108.             exclusive to CHOOSER_DropDown, one of the two MUST be TRUE.
  109.  
  110.             Defaults to FALSE.
  111.  
  112.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  113.  
  114.         CHOOSER_DropDown (BOOL)
  115.             Sets the chooser to work in dropdown mode.  Generally for
  116.             selecting an action to perform from a list of possible actions.
  117.             This item is mutually exclusive to CHOOSER_PopUp, one of the
  118.             two MUST be TRUE.
  119.  
  120.             Defaults to FALSE.
  121.  
  122.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  123.  
  124.         CHOOSER_Title (STRPTR)
  125.             Title to appear within the select box when in dropdown mode
  126.  
  127.             Defaults to NULL.
  128.  
  129.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  130.  
  131.         CHOOSER_Labels (struct List *)
  132.             Exec List of labels.  Each node must be allocated with the
  133.             AllocChooserNodeA() function.
  134.  
  135.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  136.  
  137.         CHOOSER_MaxLabels (WORD)
  138.             Set the maximum number of labels that will be displayed in the
  139.             chooser, regardless of the size of the list.
  140.  
  141.             Defaults to 12.
  142.  
  143.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  144.  
  145.         CHOOSER_Active (WORD) /* Obsolete */
  146.         CHOOSER_Selected (WORD)
  147.             Index of selected label in the list.
  148.  
  149.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET, OM_NOTIFY)
  150.  
  151.         CHOOSER_Width (WORD)
  152.             The width of the chooser menu.
  153.  
  154.             Defaults to the width of the gadget select box.
  155.  
  156.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  157.  
  158.         CHOOSER_AutoFit (BOOL)
  159.             Set the width of the chooser menu so that it fits the widest
  160.             label in the list.
  161.  
  162.             Defaults to FALSE.
  163.  
  164.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
  165. chooser_gc/--styleguide--                           chooser_gc/--styleguide--
  166.  
  167.     CHOOSER STYLE
  168.         The Chooser has two very distinct modes of operation, drop-down and
  169.         pop-up.  It is important to understand the differences between these
  170.         two modes and to use the proper mode in the proper context.
  171.  
  172.     POP-UP CHOOSERS
  173.         A popup is generally used for setting an application mode or state,
  174.         and in many cases it can replace a cycle gadget or MX (radio buttons)
  175.         gadget.  In this mode, there is a currently active item in the list
  176.         of selections, which will be display in the gadget select button.
  177.         This has the same advantage of a cycle menu in that it is compact,
  178.         with the further advantage that all values can be displayed at once
  179.         and therefore the list of values can be much larger, though generally
  180.         no more than a dozen items should be displayed.
  181.  
  182.     DROP-DOWN CHOOSERS
  183.         A dropdown chooser is for performing an action from a list of
  184.         available actions.  In this mode, the gadget select box contains a
  185.         title indicating what the actions are for.  These actions should all
  186.         be closely related, and specific to a certain context within the
  187.         application.  This can be used to replace a group of buttons, or a
  188.         cycle gadget and a button where the cycle gadget modifies the
  189.         behaviour of the button.  Since using the chooser in this mode makes
  190.         functions effectively hidden, it should generally only be used where
  191.         compactness is a signficant issue.
  192.  
  193.         An alternate use for a drop-down is to use it as a means of accessing
  194.         a "hot list" for a string or integer gadget.  For example, in a word
  195.         processor you might have a string gadget at the top of the screen for
  196.         entering the text point size.  Beside that you could have a drop-down
  197.         chooser that lists some common point sizes that would then be copied
  198.         into your integer gadget and change the text size when you make a
  199.         selection.  When a drop-down is used this way, it is generally
  200.         desirable not to have the drop-down display a title within the gadget
  201.         box (pass NULL for CHOOSER_Title) and to  make the gadget this enough
  202.         so that just the arrow is displayed (use about 20 for GA_Width if not
  203.         using the chooser within a layout group).
  204. chooser_gc/CHOOSER_GetClass                       chooser_gc/CHOOSER_GetClass
  205.  
  206.     NAME
  207.         CHOOSER_GetClass -- Gets the pointer to the chooser class.
  208.  
  209.     SYNOPSIS
  210.         chooser_class = CHOOSER_GetClass();
  211.         D0
  212.  
  213.         Class * CHOOSER_GetClass(VOID);
  214.  
  215.     FUNCTION
  216.         This function is only available in runtime linked version of the
  217.         class, and is not in the compiler linker library chooser_gc.lib.
  218.  
  219.         Obtains the pointer to the Chooser gadget class for use with
  220.         NewObject().  This function always returns a valid pointer so
  221.         you do not need to check it.  The reason is that if the library
  222.         opens fine, then the pointer returned is already setup.  (Of course
  223.         this implies that if opening the library fails, you shouldn't be
  224.         calling this.)
  225.  
  226.         Note that this function does not create the class, that is done
  227.         when the class library is opened.
  228.  
  229.     INPUTS
  230.         Nothing.
  231.  
  232.     RESULT
  233.         chooser_class - Pointer to the Chooser gadget class.
  234.  
  235.     SEE ALSO
  236. chooser_gc/AllocChooserNodeA                     chooser_gc/AllocChooserNodeA
  237.  
  238.     NAME
  239.         AllocChooserNodeA -- Allocate a Chooser node.
  240.  
  241.     SYNOPSIS
  242.         struct Node * AllocChooserNode(Tag, ...)
  243.         node = AllocChooserNode(columns, Tag, ...)
  244.  
  245.         struct Node * AllocChooserNodeA(struct TagItem *)
  246.         node = AllocChooserNodeA(taglist)
  247.  
  248.     FUNCTION
  249.         Allocates a node that can be added to the Exec linked list of
  250.         labels in the chooser.  This is the only way to allocate a
  251.         node for this list, you cannot allocate nodes yourself because
  252.         the Chooser class uses a private node structure.
  253.  
  254.     INPUTS
  255.         taglist - Attributes for the node, passed onto SetChooserNodeAttrsA().
  256.  
  257.     RESULT
  258.         node - A node that can be added into the Exec list of labels for
  259.             a Chooser gadget.
  260.  
  261.     SEE ALSO
  262.         FreeChooserNode(), SetChooserNodeAttrsA()
  263. chooser_gc/FreeChooserNode                         chooser_gc/FreeChooserNode
  264.  
  265.     NAME
  266.         FreeChooserNode -- Free a Chooser node.
  267.  
  268.     SYNOPSIS
  269.         VOID FreeChooserNode(struct Node *)
  270.         FreeChooserNode(node)
  271.  
  272.     FUNCTION
  273.         Frees a ChooserNode allocated with AllocChooserNodeA().
  274.  
  275.     INPUTS
  276.         node - The node to free.
  277.  
  278.     SEE ALSO
  279.         AllocChooserNodeA()
  280. chooser_gc/GetChooserNodeAttrsA               chooser_gc/GetChooserNodeAttrsA
  281.  
  282.     NAME
  283.         GetChooserNodeAttrsA -- Get attributes about a Chooser node.
  284.  
  285.     SYNOPSIS
  286.         VOID GetChooserNodeAttrs(struct Node *, Tag, ...)
  287.         GetChooserNodeAttrs(node, firsttag, ...)
  288.  
  289.         VOID GetChooserNodeAttrsA(struct Node *, struct TagItem *)
  290.         GetChooserNodeAttrsA(node, taglist)
  291.  
  292.     FUNCTION
  293.         The Chooser uses a private node structure and all attributes
  294.         are hidden, and must therefore be accessed with this function.
  295.  
  296.     INPUTS
  297.         node - The Chooser node to get the information on.
  298.         taglist - A tag list of attributes to get.  ti_Tag is the attribute
  299.             to get and ti_Data is a pointer to a location to copy the result
  300.             to.  The exception is LBNA_Column, which is used to specify a
  301.             column to get attributes on.
  302.  
  303.     SEE ALSO
  304.         SetChooserNodeAttrsA()
  305. chooser_gc/SetChooserNodeAttrsA               chooser_gc/SetChooserNodeAttrsA
  306.  
  307.     NAME
  308.         SetChooserNodeAttrsA -- Set attributes of a Chooser node.
  309.  
  310.     SYNOPSIS
  311.         VOID SetChooserNodeAttrs(struct Node *, Tag, ...)
  312.         SetChooserNodeAttrs(node, firsttag, ...)
  313.  
  314.         VOID SetChooserNodeAttrsA(struct Node *, struct TagItem *)
  315.         SetChooserNodeAttrsA(node, taglist)
  316.  
  317.     FUNCTION
  318.         Changes attributes for a Chooser node.  Since the Chooser
  319.         class uses a private node structure, this is the only way to change
  320.         node attributes.
  321.  
  322.         You may NOT change node attributes when the node is in a list
  323.         attached to a Chooser gadget.  You must first detach the list
  324.         with CHOOSER_Labels, ~0 before you can change attributes, and
  325.         then re-attach the list.
  326.  
  327.     TAGS
  328.         CNA_Text (STRPTR)
  329.         Text string to appear as a line in the Chooser menu. This tag
  330.         must be supplied for the node.
  331.  
  332.         CNA_Image (struct Image *)
  333.         Image to be placed to the left of the CNA_Text in the Chooser menu.
  334.  
  335.         CNA_SelImage (struct Image *)
  336.         Selected state Image to be placed to the left of the CNA_Text in
  337.         the Chooser menu.
  338.  
  339.         CNA_ReadOnly (BOOL) (V41.4)
  340.         Item will not be highlight rendered when selected.
  341.  
  342.         CNA_Disabled (BOOL) (V41.5)
  343.         Item can not be selected. No GADGETUP message is generated.
  344.  
  345.         CNA_Separator (BOOL) (V41.7)
  346.         Separator (~~~~) Bar Item can not be selected. Simular to the
  347.         separator bars in Intuition menus. No GADGETUP message is generated.
  348.  
  349.     INPUTS
  350.         node - Node whose attributes you are changing.
  351.         taglist - Tag list of attributes to change.
  352.  
  353.     SEE ALSO
  354.         GetChooserNodeAttrsA()
  355.